C++ Pimpl 惯用法：编译防火墙与二进制兼容
C++ 类的私有成员写在头文件里，等于把实现细节暴露给了每一个包含这个头文件的编译单元：实现一变，所有依赖者重新编译；类布局一变，库的二进制接口（ABI）跟着变。Pimpl（pointer to implementation，指向实现的指针）用一个指针把实现细节从头文件里整体挪走，是处理这类问题的经典手法，也被称为「编译防火墙」（compilation firewall）或「柴郡猫」（Cheshire cat）。本文整理它的动机、结构与实现要点。
要解决的三类问题
- 编译依赖传染。私有成员的类型需要出现在头文件里，
#include顺着头文件链路扩散到所有使用者——哪怕这些成员对外完全不可见。 - 编译时间。头文件里任何一处改动（哪怕只是给私有成员加了个字段）都会让所有包含它的编译单元重新编译，大型项目里代价显著。
- 二进制兼容（ABI）。给类加成员会改变对象布局，已编译的调用方代码按旧布局访问就是未定义行为。库想在不重新编译使用者的前提下升级，就必须保证对象布局不变。
基本结构
Pimpl 的做法分三层：
- 接口类（对外）：头文件中只保留公共接口，前向声明 Impl 类，不出现任何私有数据；
- 实现类（对内）：只在
.cpp文件中定义，容纳全部私有数据与业务逻辑； - 指针连接：接口类通过智能指针（通常是
std::unique_ptr）持有 Impl 实例，所有接口方法转发给 Impl 执行。
头文件（接口类）：
cpp
// MyInterface.h
#pragma once
#include <memory>
class MyInterface {
public:
MyInterface();
~MyInterface();
void doSomething();
private:
class Impl; // 前向声明，定义在 .cpp
std::unique_ptr<Impl> pimpl;
};源文件（实现类）：
cpp
// MyInterface.cpp
#include "MyInterface.h"
class MyInterface::Impl {
public:
void doSomethingImpl();
// 私有数据和实现细节全部在这里
};
MyInterface::MyInterface() : pimpl(std::make_unique<Impl>()) {}
MyInterface::~MyInterface() = default;
void MyInterface::doSomething() {
pimpl->doSomethingImpl();
}
void MyInterface::Impl::doSomethingImpl() {
// 具体实现逻辑
}此后再怎么修改 Impl 的成员，MyInterface.h 都不用动：头文件稳定，依赖它的编译单元不必重编；接口类对象始终只含一个指针，布局不变，ABI 稳定。
析构函数为什么必须在 .cpp 里定义
上面的例子里，~MyInterface() 在头文件声明、在 .cpp 中 = default，这不是风格偏好，而是编译期的硬约束：std::unique_ptr 的删除器在析构点要求 Impl 是完整类型，而头文件里只有前向声明。如果析构函数直接定义在头文件里（包括隐式生成的），编译器会在成员需要被销毁的位置找不到 Impl 的定义而报错。
同样的约束适用于移动构造与移动赋值：这些特殊成员函数都要么在头文件声明、.cpp 中定义（哪怕是 = default），要么显式禁用。拷贝操作则需要自行定义（深拷贝 Impl），或直接 = delete。
得与失
| 收益 | 代价 |
|---|---|
编译防火墙：Impl 改动只重编接口类自己的 .cpp | 每次成员访问多一次指针间接寻址 |
头文件干净，#include 不再扩散 | Impl 对象需要堆分配，缓存局部性变差 |
| ABI 稳定，库可独立升级 | 每个类多一份样板代码（声明/定义拆两处） |
| 实现细节完全隐藏 | 生命周期管理责任在接口类一侧 |
适用场景
- 库的公共 API：使用方只依赖稳定的头文件，库内部可以自由演进；
- 编译时间热点：被广泛包含的头文件改成 Pimpl 后，改实现不再触发全局重编；
- 需要 ABI 稳定的 SDK：跨版本保持对象布局不变。
反过来，进程内部的小工具类、性能敏感的内层路径（每次间接寻址都有代价）、本来就无外部使用者的实现类，通常不值得引入这层间接。
结语
- Pimpl 用「接口类持指针 + 实现类全在
.cpp」换编译隔离与 ABI 稳定，代价是指针间接、堆分配和样板代码； - 特殊成员函数（析构、移动）必须在
.cpp中定义，根源是std::unique_ptr删除器要求完整类型； - 是否使用取决于场景：公共 API 与编译热点收益最大，内部小类不必强加。